/* 
 * Enterprise Library Extensions - DI + ORM.
 * Copyright (C) 2006
 *
 * GNU General Public License
 *
 * This program is free software; you can redistribute 
 * it and/or modify it under the terms of the GNU General Public License 
 * as published by the Free Software Foundation; either version 2 of the 
 * License, or (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful, but 
 * WITHOUT ANY WARRANTY; without even the implied warranty of 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 
 * See the GNU General Public License for more details.
 */
using System;
using System.Collections.Generic;
using System.Text;
using System.Data;

namespace ELE.EnterpriseLibrary.Data
{
  /// <summary>
  /// Implementations of this interface are meant to provide functionality for building sql
  /// queries based on the definitions specified in <see cref="ObjectSqlMapping"/> objects.
  /// <para>Implementations are specific to the underlying RDBMS system's implementation of 
  /// the SQL standard.</para>
  /// </summary>
  public interface ISqlQueryBuilder
  {
    /// <summary>
    /// Builds a SQL query to retrieve an object by using the primary binding in an
    /// object mapping instance. In other words it builds a query that selects records
    /// from a relational database based on the primary key of a table defined as the 
    /// primary table of an object sql mapping.
    /// </summary>
    /// <param name="objectMapping">The mapping definition.</param>
    /// <returns>The built SQL statement to retrieve records by a primary key.</returns>
    string BuildSqlQueryString(ObjectSqlMapping objectMapping);
    /// <summary>
    /// Builds a SQL query to retrieve an object based on a property of the object that is
    /// bound to a table column as defined in the given object mapping.
    /// </summary>
    /// <param name="objectMapping">The mapping that defines how the property is bound to the table column.</param>
    /// <param name="propertyName">The name of the property we are interested in.</param>
    /// <returns>The SQL statement that selects objects by a matching property.</returns>
    string BuildSqlQueryString(ObjectSqlMapping objectMapping, string propertyName);
    /// <summary>
    /// Builds a SQL statement that inserts data from properties of an object that are mapped to 
    /// columns in database tables.
    /// </summary>
    /// <param name="mapping">The mapping that defines the relationships between columns and properties.</param>
    /// <param name="tableName">The name of the table within the mapping that the insert statement is 
    /// to be built for.</param>
    /// <returns>The SQL statement.</returns>
    string BuildSqlInsertString(ObjectSqlMapping mapping, string tableName);
    /// <summary>
    /// Builds a SQL statement that makes updates from properties of an object that are mapped to 
    /// columns in database tables to matched records in those tables via primary key bindings.
    /// </summary>
    /// <param name="mapping">The mapping that defines the relationships between columns and properties.</param>
    /// <param name="tableName">The name of the table within the mapping that the update statement is 
    /// to be built for.</param>
    /// <returns>The SQL statement.</returns>
    string BuildSqlUpdateString(ObjectSqlMapping mapping, string tableName);
    /// <summary>
    /// Builds a SQL statement that deletes data from the database tables whose primary key matches the value of 
    /// an object's property that is bound to a primary key.
    /// </summary>
    /// <param name="mapping">The mapping that defines the relationships between columns and properties.</param>
    /// <param name="tableName">The name of the table within the mapping that the delete statement is 
    /// to be built for.</param>
    /// <returns>The SQL statement.</returns>
    string BuildSqlDeleteString(ObjectSqlMapping mapping, string tableName);
    /// <summary>
    /// Given a data reader with the cursor properly pointed to a row, retrieve the value of the column in the 
    /// row that matches the position defined by the given index. Use the given sqlType string representation 
    /// to cast the <see cref="DbType"/> of the value in the matched column into a .NET object that matches 
    /// the provided objectType.
    /// </summary>
    /// <param name="reader">The reader.</param>
    /// <param name="index">The index of the column in the current row that holds the wanted value.</param>
    /// <param name="sqlType">The string representation of the type. See 
    /// <seealso cref="ISqlParser.GetDbTypeFromString(string)"/> for clues on the meaning of string representation of db types.</param>
    /// <param name="objectType">The system or .NET type that is to be resulted.</param>
    /// <returns>The actual value held in the column at index in the reader's current row, casted to objectType.</returns>
    object CastObjectFromReader(IDataReader reader, int index, string sqlType, Type objectType);
    /// <summary>
    /// The internal implementation of the <see cref="ISqlParser"/> interface, specific to this RDBMS.
    /// </summary>
    ISqlParser SqlParser { get; }
  }
}
